.so ../bk-macros
.TH "bk bam" "\*[BKVER]" %D% "\*(BC" "\*(UM"
.SH NAME
bk bam \- BAM utility routines
.SH SYNOPSIS
.B bk bam check 
.[B] \-Fq
.br
.B bk bam clean
.[B] \-an
.br
.B bk bam convert
.[ARG] size
.br
.B bk bam pull
.[B] \-aq
.[ARG] URL
.br
.B bk bam push
.[B] \-q
.[ARG] URL
.br
.B bk bam reattach
.[B] \-q
.ARG -
.br
.B bk bam reload
.br
.B bk bam repair
.[B] \-q
.[OPTreq] \-@ URL
.br
.B bk bam server
.[B] \-flqrs
.[ARG] URL
.SH DESCRIPTION
\*(BK Binary Asset Management (BAM) is a subfeature that provides
support for large binary files, such as tool chains, cell
libraries, game data, etc.
BAM differs from traditional binary storage in that the data does not need
to be replicated in all clones, it may be lazily fetched on demand from
a BAM server.
.LP
The
.B bk bam
command is a utility command which provides interfaces for checking 
integrity of BAM files,
removing "orphaned" BAM files,
converting old binary files to BAM files,
fetching BAM files from the BAM server,
pushing local BAM files to the BAM server,
or repairing a BAM pool.
In general, the convert or pull interfaces are most likely to be useful, 
the others are typically used debugging.
.LP
In any operation with a 
.Q \-q
option, that option means to run quietly.
The operations supported are:
.TP \fBreattach\fP
.B check
Check that the BAM files are present and are not corrupted.
If the
.Q \-F
option is included, then the corruption check is skipped.
Any files which are not found locally are looked for in the BAM server.
Note: currently there is no way to check for corruption remotely.
.tp
.B clean
Remove any BAM files that are not referenced by any delta in the repository.
If the
.Q \-a
option is included, then flush local BAM files which are copies from the 
BAM server.
If the
.Q \-n
option is included, then just say what would be done but do not do it.
.br
NOTE: this command should 
.B never 
be run in a BAM server since the server may have BAM files referenced
only by clients.
.tp
.B convert
Convert all files from traditional binary encoding to BAM encoding.
Only files greater than a certain size are converted since small files 
perform better with the traditional encoding.
The size, which defaults to 64K, is compared against the initial version
of each binary file, and if that version is greater than the size the file
is converted.
Note that the conversion may be run more than once, but the size used
can only decrease, it may not increase.
.tp
.B pull
This interface is used to transfer any BAM data that is missing from the
current repository or its BAM server.  This is useful to request any missing
BAM data after switching to a new BAM server.
With the
.B \-a
option the local BAM server is ignored, so all BAM data will be requested.
Normally, the local BAM pool contains only those files which have been either
checked out locally or created locally, i.e., the BAM pool is sparse.
This command may be useful to populate a laptop clone with all revisions
for disconnected operation or to set up a new BAM server.
.tp
.B push
This interface is used to populate a BAM server with any BAM files which
have been created locally but not sent to the server.
In general, this command is not needed because the BAM server is automatically
updated if the local BAM files are either cloned or pulled to another repo.
.tp
.B reattach
Used to try and reinsert data into the BAM directory.
If your disk crashed and some files were lost from the BAM directory
(which bk bam check -F will tell you) and you believe you have that 
data, you can tell bk bam reattach to put it back.
.sp .5
For each file specified on standard input, see if the hash of the file matches
one of the missing files.
If so, reinsert that file.
.\" XXX - tell them that it may be wrong?
.tp
.B reload
The BAM pool has an on disk binary index that is used for fast lookups
stored in:
.DS
BitKeeper/BAM/\*<repo-rootkey\*>/index.db
.DE
The data is also stored in a text format index:
.DS
BitKeeper/BAM/\*<repo-rootkey\*>/BAM.index
.DE
Should the binary index get corrupted, it may be recreated running this command.
.tp
.B repair
Similar to 
.B bk bam check
except that it will attempt to repair any corrupted data.
By default, it will look for good data in the BAM server, but you may
specify a different location with
.[OPTreq] \-@ URL
(which may be repeated).
.tp
.B server
Used to report or, with the optional 
.ARG URL ,
set the BAM server from which BAM data will be fetched.
If the
.Q \-r
option is set then the current server URL is deleted.
When the BAM server is changed, this command will automatically query the
new server and transfer any BAM data it is missing from the old BAM
server.
This query and transfer may be suppressed with the
.Q \-s
option.
Use the
.Q \-f
option to force changing or removing the BAM server setting if the
repository is currently defined as a BAM server.
The
.Q \-l
option causes the existing BAM server URL to be printed for
scripts.
And
.Q \-q
can be used to suppress status messages when the URL is changed.
.SH SEE ALSO
.SA Howto-BAM
.SH CATEGORY
.B Utility
.\" help://BAM
